<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Transaction FAQ</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="transapp.html" title="Chapter 11.  Berkeley DB Transactional Data Store Applications" />
    <link rel="prev" href="transapp_throughput.html" title="Transaction throughput" />
    <link rel="next" href="rep.html" title="Chapter 12.  Berkeley DB Replication" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Transaction FAQ</th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="transapp_throughput.html">Prev</a> </td>
          <th width="60%" align="center">Chapter 11. 
		Berkeley DB Transactional Data Store Applications
        </th>
          <td width="20%" align="right"> <a accesskey="n" href="rep.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="sect1" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title" style="clear: both"><a id="transapp_faq"></a>Transaction FAQ</h2>
          </div>
        </div>
      </div>
      <div class="orderedlist">
        <ol type="1">
          <li>
            <p>
            <span class="bold"><strong>What should a transactional program do when an error occurs?</strong></span>
        </p>
            <p>
            Any time an error occurs, such that a transactionally protected
            set of operations cannot complete successfully, the transaction
            must be aborted.  While deadlock is by far the most common of
            these errors, there are other possibilities; for example,
            running out of disk space for the filesystem.  In Berkeley DB
            transactional applications, there are three classes of error
            returns: "expected" errors, "unexpected but recoverable"
            errors, and a single "unrecoverable" error.  Expected errors
            are errors like 
            <a class="link" href="program_errorret.html#program_errorret.DB_NOTFOUND">DB_NOTFOUND</a>,
            which indicates that a searched-for key item is not present in
            the database.  Applications may want to explicitly test for and
            handle this error, or, in the case where the absence of a key
            implies the enclosing transaction should fail, simply call
            <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN-&gt;abort()</a>.  Unexpected but recoverable errors are errors like
            <a class="link" href="program_errorret.html#program_errorret.DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>,
            which indicates that an operation has been selected to resolve
            a deadlock, or a system error such as EIO, which likely
            indicates that the filesystem has no available disk space.
            Applications must immediately call <a href="../api_reference/C/txnabort.html" class="olink">DB_TXN-&gt;abort()</a> when these
            returns occur, as it is not possible to proceed otherwise.  The
            only unrecoverable error is 
            <a class="link" href="program_errorret.html#program_errorret.DB_RUNRECOVERY">DB_RUNRECOVERY</a>,
            which indicates that the system must stop and recovery must be
            run.
      </p>
          </li>
          <li>
            <p>
          <span class="bold"><strong>How can hot backups work?  Can't you get an
              inconsistent picture of the database when you copy
              it?</strong></span>
        </p>
            <p>
            First, Berkeley DB is based on the technique of "write-ahead
            logging", which means that before any change is made to a
            database, a log record is written that describes the change.
            Further, Berkeley DB guarantees that the log record that
            describes the change will always be written to stable storage
            (that is, disk) before the database page where the change was
            made is written to stable storage.  Because of this guarantee,
            we know that any change made to a database will appear either
            in just a log file, or both the database and a log file, but
            never in just the database.
        </p>
            <p>
            Second, you can always create a consistent and correct database
            based on the log files and the databases from a database
            environment.  So, during a hot backup, we first make a copy of
            the databases and then a copy of the log files.  The tricky
            part is that there may be pages in the database that are
            related for which we won't get a consistent picture during this
            copy.  For example, let's say that we copy pages 1-4 of the
            database, and then are swapped out.  For whatever reason
            (perhaps because we needed to flush pages from the cache, or
            because of a checkpoint), the database pages 1 and 5 are
            written.  Then, the hot backup process is re-scheduled, and it
            copies page 5.  Obviously, we have an inconsistent database
            snapshot, because we have a copy of page 1 from before it was
            written by the other thread of control, and a copy of page 5
            after it was written by the other thread.  What makes this work
            is the order of operations in a hot backup.  Because of the
            write-ahead logging guarantees, we know that any page written
            to the database will first be referenced in the log.  If we
            copy the database first, then we can also know that any
            inconsistency in the database will be described in the log
            files, and so we know that we can fix everything up during
            recovery.
        </p>
          </li>
          <li>
            <p>
            <span class="bold"><strong>My application has <a class="link" href="program_errorret.html#program_errorret.DB_LOCK_DEADLOCK">DB_LOCK_DEADLOCK</a>
                errors.  Is the normal, and what should I do?</strong></span>
        </p>
            <p>
            It is quite rare for a transactional application to be deadlock
            free.  All applications should be prepared to handle deadlock
            returns, because even if the application is deadlock free when
            deployed, future changes to the application or the Berkeley DB
            implementation might introduce deadlocks.
        </p>
            <p>
            Practices which reduce the chance of deadlock include:

</p>
            <div class="itemizedlist">
              <ul type="disc">
                <li>Not using cursors which move backwards through the database (<a href="../api_reference/C/dbcget.html#dbcget_DB_PREV" class="olink">DB_PREV</a>),
as backward scanning cursors can deadlock with page splits;</li>
                <li>Configuring <a href="../api_reference/C/dbset_flags.html#dbset_flags_DB_REVSPLITOFF" class="olink">DB_REVSPLITOFF</a> to turn off reverse splits in
applications which repeatedly delete and re-insert the same keys, to
minimize the number of page splits as keys are re-inserted;</li>
                <li>Not configuring <a href="../api_reference/C/dbopen.html#dbopen_DB_READ_UNCOMMITTED" class="olink">DB_READ_UNCOMMITTED</a> as that flag requires write
transactions upgrade their locks when aborted, which can lead to deadlock.
Generally, <a href="../api_reference/C/dbcget.html#dbcget_DB_READ_COMMITTED" class="olink">DB_READ_COMMITTED</a> or non-transactional read operations
are less prone to deadlock than <a href="../api_reference/C/dbopen.html#dbopen_DB_READ_UNCOMMITTED" class="olink">DB_READ_UNCOMMITTED</a>.</li>
              </ul>
            </div>
            <p>
        </p>
          </li>
          <li>
            <p>
            <span class="bold"><strong>How can I move a database from one
                transactional environment into another?</strong></span>
        </p>
            <p>
            Because database pages contain references to log records,
            databases cannot be simply moved into different database
            environments.  To move a database into a different environment,
            dump and reload the database before moving it.  If the database
            is too large to dump and reload, the database may be prepared
            in place using the <a href="../api_reference/C/envlsn_reset.html" class="olink">DB_ENV-&gt;lsn_reset()</a> method or the <span class="bold"><strong>-r</strong></span> argument to the <a href="../api_reference/C/db_load.html" class="olink">db_load utility</a>.
        </p>
          </li>
          <li>
            <p>
            <span class="bold"><strong>I'm seeing the error "log_flush: LSN past
                current end-of-log", what does that mean?</strong></span>
        </p>
            <p>
            The most common cause of this error is that a system
            administrator has removed all of the log files from a database
            environment.  You should shut down your database environment as
            gracefully as possible, first flushing the database environment
            cache to disk, if that's possible.  Then, dump and reload your
            databases.  If the database is too large to dump and reload,
            the database may be reset in place using the <a href="../api_reference/C/envlsn_reset.html" class="olink">DB_ENV-&gt;lsn_reset()</a>
            method or the <span class="bold"><strong>-r</strong></span> argument to
            the <a href="../api_reference/C/db_load.html" class="olink">db_load utility</a>.  However, if you reset the database in place,
            you should verify your databases before using them again.  (It
            is possible for the databases to be corrupted by running after
            all of the log files have been removed, and the longer the
            application runs, the worse it can get.)
        </p>
          </li>
        </ol>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="transapp_throughput.html">Prev</a> </td>
          <td width="20%" align="center">
            <a accesskey="u" href="transapp.html">Up</a>
          </td>
          <td width="40%" align="right"> <a accesskey="n" href="rep.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Transaction throughput </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Chapter 12. 
		Berkeley DB Replication
        </td>
        </tr>
      </table>
    </div>
  </body>
</html>
